/*
 *  SPAGL Copyright (C) 2008 Sam Pottinger
 *  This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser 
 *  General Public License as published by the Free Software Foundation; either version 2.1 of the License, or 
 *  (at your option) any later version. This library is distributed in the hope that it will be useful, but 
 *  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
 *  See the GNU Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License along with this library; if not, 
 *  write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 
 */

package spagcore;

/**
 * A widget/container to organize a set of radio buttons
 * @see SpaglCoreRadioButton
 * @author Sam Pottinger
 */
public interface SpaglCoreRadioGroup extends SpaglCoreWidget, SpaglCoreEventGenerator {
	
	/**
	 * Adds a new radio button to this widget using the default layout settings
	 * @param newButton The radio button (that conforms to SpaglCoreRadioButton) to be added
	 * @return The button (as a SpaglCoreRadioButton) that was just added
	 */
	public SpaglCoreRadioButton addButton(SpaglCoreRadioButton newButton);
	
	/**
	 * Adds a new radio button to this widget with the specified layout settings
	 * @param newButton The radio button (that conforms to SpaglCoreRadioButton) to be added
	 * @param placementParameters The string parameters to be used to place this widget
	 * @return The button (as a SpaglCoreRadioButton) that was just added
	 */
	public SpaglCoreRadioButton addButton(SpaglCoreRadioButton newButton, String placementParameters);
	
	/**
	 * Creates a new SpaglRadioButton with the given text and uses the layout manager's default behavior
	 * @param newText The text of the new radio button
	 * @return The button (as a SpaglCoreRadioButton) that was just added
	 */
	public SpaglCoreRadioButton addButton(String newText);
	
	/**
	 * Creates a new SpaglRadioButton with the given text and uses the specified parameters to place this widget
	 * @param newText The text of the new radio button
	 * @param placementParameters The string parameters to be used to place this widget
	 * @return The button (as a SpaglCoreRadioButton) that was just added
	 */
	public SpaglCoreRadioButton addButton(String newText, String placementParameters);
	
	/**
	 * Gets the index of the selected button
	 * @return The integer index of the selected button
	 */
	public int getSelectedIndex();
	
	/**
	 * Gets the SpaglCoreRadioButton object that is selected by the user
	 * @return The radio button selected as a SpaglCoreRadioButton
	 */
	public SpaglCoreRadioButton getSelectedButton();
	
	/**
	 * Sets the selected radio button
	 * @param newSelection The index of the radio button to be selected
	 */
	public void setSelection(int newSelection);
	
	/**
	 * Sets the selected radio button
	 * @param newSelection The radio button object to be selected
	 */
	public void setSelection(SpaglCoreRadioButton newSelection);
	
	/**
	 * Gets an array of radio buttons associated with this widget
	 * @return An array of SpaglCoreRadioButtons that are inside this widget
	 */
	public SpaglCoreRadioButton[] getButtons();
	
	/**
	 * Removes the button belonging to this widget at given index
	 * @param i The index of the button to be removed
	 */
	public void removeButton(int i);

}
